home *** CD-ROM | disk | FTP | other *** search
/ Super Shareware Collection / Super Shareware Collection.iso / os_2 / epmgcc10.zip / INSTALL.DOC < prev    next >
Text File  |  1994-01-28  |  16KB  |  339 lines
  1.                          EMX/GCC Interface to EPM 5.51
  2.  
  3.                              EPMGCC Version  1.00
  4.  
  5.                                Bernhard Bablok
  6.  
  7.                                 January, 1994
  8.  
  9. Legal stuff:
  10. ~~~~~~~~~~~
  11. See the file license.txt.
  12.  
  13.  
  14. Requirements:
  15. ~~~~~~~~~~~~
  16. The EMX/GCC interface to EPM supplied with this package needs to be compiled
  17. before it can be incorporated into EPM.  You will need to obtain the complete
  18. EPM 5.51 package from IBM to do this.
  19.  
  20. The EPM package is available for free from the following Internet sites:
  21.  
  22. software.watson.ibm.com   /pub/os2/os2fixes
  23. ftp-os2.nmsu.edu          /pub/os2/ibm/os2fixes
  24.  
  25. It should also be available from major OS/2 BBS services.
  26.  
  27. Note: With OS2 2.1, EPM 5.51 is part of OS2. You still need to obtain the
  28.       complete package, since you need the source code of the standard set of
  29.       e-macros.
  30.  
  31.  
  32. Introduction:
  33. ~~~~~~~~~~~~
  34. (Skip this section if you are familiar with configuring and compiling EPM).
  35.  
  36. To understand how the menu and function key support for EMX/GCC is implemented,
  37. one has to understand how IBM's Enhanced Editor EPM works. EPM consists of one
  38. exe-file (EPM.EXE) and a few "ex"-files, normaly at least "epm.ex" and
  39. "extra.ex". EPM.EXE supplies the PM-interface (eg. message-queue), while the
  40. ex-files implement the functionality of the editor via compiled macros. Each
  41. ex-file is called a module and consists of definitions of editor commands,
  42. internal procedures, menus, keys and so on. These definitions are written in a
  43. macro language called "E", which is similar but not identical to REXX. The
  44. source files have the extension "e".
  45.  
  46. Each module is the result of a compilation process of a source file. It is
  47. possible to include other source files in a sort of "master source file".
  48. Normally, the whole set of standard macros are compiled into two modules, epm.ex
  49. and extra.ex. The reason for this is that a module is limited in size to 64k.
  50. These two modules are loaded at startup of the editor. Additional modules can be
  51. loaded later.
  52.  
  53. Including source files into a master source file allows not only for an easier
  54. maintenance of code, but allows the inclusion of files depending on
  55. configuration constants (similar to #ifdef #include ... #endif structures in C).
  56.  
  57. Configuring EPM and adding own applications is made very simple through a trick.
  58. The standard set of E-macros include a number of MY*.E files. These files are
  59. the only ones which have to be changed. Once the MY*.E files are set up, only
  60. epm.e and extra.e have to be recompiled and the modules have to be located in a
  61. place where the editor can find them.
  62.  
  63. The following sections deal with the installation of EPM 5.51 and the
  64. modifications necessary on the MY*.E files to install EPMGCC.
  65.  
  66.  
  67. Installation of EPM 5.51:
  68. ~~~~~~~~~~~~~~~~~~~~~~~~
  69. Note: This section is taken from the install.doc file of EPMTEX13, written by
  70.       Jon Hacker.  If you are using TeX, I recommend this package - it adds
  71.       menu support to EPM to be used with TeX.  Without this package, I would
  72.       have probably not succeeded in writing EPMGCC.  The package is
  73.       available for free from various ftp-sites.
  74.  
  75. If you are not already familiar with compiling EPM macros on your machine, read
  76. this section for additional help.
  77.  
  78. The installation of the EPM 5.51 package is sufficiently confusing that I will
  79. try to give some hints to get you going as fast as possible.
  80.  
  81. The EPM package includes two hypertext files; the EPM User's Manual, and the EPM
  82. Technical Reference.  Both of these manuals provide a wealth of information on
  83. EPM.  It is highly recommended that you spend some time becoming familiar with
  84. EPM, and the E macro language by reading through them.
  85.  
  86.  
  87. 1) Decide on a location for your EPM files.  I suggest something like
  88.    \os2\epm or \epm.  I would avoid using the \os2\apps directory
  89.    where the binaries for EPM 5.50 are placed in the GA release of OS/2 2.0.
  90.    There's just too much other crap in there already.
  91.  
  92. 2) Unzip the EPM 5.51 files.  You will want to take care where you put
  93.    everything.  I recommend the following directory structure as suggested in
  94.    the EPMBBS.TXT file in the EPM package from IBM.
  95.  
  96. EPMAPP.ZIP - Unzip into your epm directory (eg \os2\epm)
  97.    EPM.EXE     - The 5.51 version of the editor
  98.    ETPM.EXE    - The 5.51 version of the macro compiler
  99.    PMMORE.EXE  - Useful for debugging Rexx macros; entering RXSHELL from
  100.                  EPM will start PMMORE and redirect STDOUT to this window.
  101.                  SAY and TRACE output will be displayed there.
  102.    *.EX        - the 5.51 version of the compiled macros
  103.    EPMHELP.QHL - the updated "quick help" file
  104.    EPMTECH.NDX - An index file for getting macro programmer help.
  105.  
  106. EPMBK.ZIP - Unpack into a directory in your BOOKSHELF path
  107.    EPMUSERS.INF - The EPM User's Guide
  108.    EPMTECH.INF  - The EPM Macro Programmer's Technical Reference
  109.  
  110. EPMDLL.ZIP - Unpack into \os2\apps\dll or a directory in your LIBPATH. Delete
  111.              the obsolete ETK*550.DLL files leftover from EPM 5.50.
  112.     ETK*551.DLL - The E Toolkit DLLs.
  113.  
  114. EPMMAC.ZIP - Create a subdirectory under EPM called E_MACROS and unzip into it.
  115.      *.e - contains the macro files used to build the standard *.ex files.
  116.  
  117. EPMHLP.ZIP - Updated EPM.HLP; unpack into \os2\help
  118.  
  119. EMPSMP.ZIP - Create a subdirectory under EPM called sampmacs and unzip this file
  120.              into it.
  121.      *.e - Sample E macro code; includes both useful programs and
  122.            building blocks that you can use in writing your own code.
  123.  
  124. EPMREX.ZIP - Create a subdirectory under EPM called EREXX, unzip this file into
  125.              it and add it to your EPMPATH.
  126.      *.erx - contains some sample EPM / Rexx macros.
  127.  
  128. EPMASI.ZIP - Create a subdirectory under EPM called myassist, unzip this file
  129.              into it and add it to your EPMPATH.
  130.      An alternative approach to syntax-assisted editing; makes it easy to
  131.      add your own expansions.  Includes sample files for OS/2 and PM APIs,
  132.      C, and Bookmaster.
  133.  
  134. EPMATR.ZIP - Create a subdirectory under EPM called epmattr, unzip this file
  135.              into it and add it to your EPMPATH.
  136.      Sample code for doing things with EPM's attribute support.
  137.  
  138.  
  139. 3) Edit your config.sys file and make sure that your new epm directory
  140.    is included in you PATH statement.  If you have IBM's TCP/IP networking
  141.    package, make sure your epm directory comes before \tcpip\bin in your PATH,
  142.    or delete the redundant EPM files as outlined in step (6).
  143.  
  144. 4) Edit your config.sys file and make sure that the e_macros, sampmacs,
  145.    erexx, myassist, and epmattr subdirectories are included in your EPMPATH.
  146.    EPMPATH is used by the ETPM compiler to find macro files that are not in your
  147.    current directory.
  148.  
  149. 5) Use a file finding utility to hunt down all *.ex files.  These are
  150.    the compiled E macros that EPM executes.  The GA release of OS/2 puts them
  151.    in \os2\apps.  Delete all redundant or older *.ex files on your system.  You
  152.    only need them in your EPM directory.  Having multiple copies of the *.ex
  153.    files may result in strange behaviour from EPM.
  154.  
  155. ----- OPTIONAL -------------------------------------------------------------
  156. 6) If you have IBM's TCP/IP networking package, there will be some more *.ex
  157.    files in \tcpip\bin.  You can delete most of these files, or, if you prefer,
  158.    just make sure your your epm directory comes before \tcpip\bin in your PATH,
  159.  
  160. WARNING: LEAVE THE FOLLOWING UNIQUE TO LAMAIL *.EX FILES IN \TCPIP\BIN
  161.                              ~~~~~~
  162.           EPMLIST.EX
  163.           LAMEXTRA.EX
  164.           MAILLIST.EX
  165. -----------------------------------------------------------------------------
  166.  
  167. 7) Find all copies of EPM.EXE (v 5.50) and delete them.  Likely hiding places
  168.    are \os2\apps and \tcpip\bin.  You only need the one copy of epm.exe and it
  169.    should be in your epm directory.  As long as it is in your PATH lamail will
  170.    find it.
  171.  
  172. 8) Find all copies of ETK*550.DLL (v 5.50 dll's) and delete them.  Likely
  173.    hiding places are \os2\apps\dll  and \tcpip\dll.  You only need the v5.51
  174.    dll's and they should be put somewhere in your LIBPATH (\os2\apps\dll is as
  175.    good as any) As long as it is in your LIBPATH lamail will find it.
  176.  
  177.  
  178. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  179. NOTE: Unfortunately, when you apply a CSD or Service Pack, copies of
  180.       EPM will again be placed in \os2\apps or \tcpip\bin and you will need
  181.       to do some housekeeping to get things back in order.
  182. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  183.  
  184. 9)  I advise you get the spell checker option EPM_SPEL.ZIP for EPM.  It is a
  185.     nice thing to have and is available from the following INTERNET source.
  186.  
  187.                ftp-os2.nmsu.edu          /pub/os2/2.0/editors
  188.  
  189.     You will need to put the location of the dictionary (us.dct file) in the
  190.     paths section of the EPM preferences notebook.  I put mine in
  191.     \os2\dictionary.
  192.  
  193. 10) You should now be ready to compile your E macros.  First, though, reboot
  194.     if you made any changes to config.sys.
  195.  
  196.  
  197. Configuring the editor:
  198. ~~~~~~~~~~~~~~~~~~~~~~
  199. "Configuring the editor" means the definition of constants which define the
  200. behavior of the editor like colors, appearance of the mouse, mark-mode and (very
  201. important!) which macros of the standard set are included into the two
  202. base-modules epm.ex and extra.ex. Configuring is not only important to make EPM
  203. look and act like you expect it to do, but also to save space. For example, I
  204. have thrown out all macros which implement the host support, since my PC is not
  205. connected to a host. Space is needed for additional applications and to minimize
  206. startup time of the editor.
  207.  
  208. Configuration is done by setting up a file called MYCNF.E. This file is included
  209. by various e-macro source file to alter the code at compile time.
  210.  
  211. Read the section in the EPM user's manual 'Changing the default configuration'
  212. to understand the use of EPM's configuration constants and what they can do.
  213. The binaries included with the EPM package were compiled with the constants
  214. defined in epmgcnf.smp in your e_macros subdirectory.  If these are OK with you,
  215. copy epmgcnf.smp to a file called mycnf.e in your e_macros directory.  I have
  216. also included a file MYCNF.SMP as an example of a configuration file (it is the
  217. one I use).
  218.  
  219. Important note: Never put any executable e-code in MYCNF.E!
  220.  
  221.  
  222. Implementing EPMGCC:
  223. ~~~~~~~~~~~~~~~~~~~
  224. Any additional applications should be implemented via the MY*.E files. They are
  225. included automatically at the right place. The following files are supplied as
  226. samples (extension "smp" instead as "e"):
  227.  
  228. MYKEYS.E    This file should include application key definitions. It is better
  229.             to use "TRYINCLUDE" statements, so you don't have to change this
  230.             file if a new version of an application is to be used. The sample
  231.             file consists of a single statement:
  232.                  TRYINCLUDE 'gcckeys.e'.
  233.             The included file defines some accelerator keys and the
  234.             "next-error-key".  If the defined keys conflict with key definitions
  235.             of other applications, you would have to edit gcckeys.e.
  236.  
  237. MYSTUFF.E   All includes for application macros which should go into the module
  238.             epm.ex. Note that the size of epm.ex is limited to 64k. The sample
  239.             file consists of two statements (since I also use EPMTEX13):
  240.                  TRYINCLUDE 'tex.e'
  241.                  TRYINCLUDE 'gcc.e'
  242.             If you do not have EPMTEX13, you do not have to remove the first
  243.             line - it is ignored by the macro compiler.
  244.  
  245. MYMNUINI.E  This file is included by the standard macro which implements the
  246.             menu support. If applications need menu support, their code should
  247.             be included into this file. Again, the sample consists of two
  248.             statements:
  249.                  TRYINCLUDE 'texmenu.e'
  250.                  TRYINCLUDE 'gccmenu.e'
  251.             Note to EPMTEX13 users: I have renamed the file mymnuini.e supplied
  252.             with EPMTEX13 to texmenu.e.
  253.  
  254. Important note: The set of internal procedures and command definitions used by
  255.                 EPMGCC is not part of epm.ex due to size limitations. The file
  256.                 gccproc.e has to be compiled seperately (see below). The
  257.                 resulting module is loaded automatically after startup of the
  258.                 editor.
  259.  
  260.  
  261. Configuring EPMGCC:
  262. ~~~~~~~~~~~~~~~~~~
  263. EPMGCC offers two levels of configuration. You can define the utilities
  264. (compiler, make, debugger) which are invoked by the various menu-selections.
  265. These definitions cannot be changed after the compilation of the edit-macros.
  266.  
  267. In addition you can define startup values for the compile/build-options and for
  268. the debug, autosave and verbose toggles.  These values can be changed at runtime
  269. but they cannot be saved from session to session.
  270.  
  271. Configuration is done in a file called GCCENV.E. The main idea is that you don't
  272. have to change the configuration file when a new version of EPMGCC becomes
  273. available.
  274.  
  275. The file gccenv.smp reproduces the defaults used if no gccenv.e file is found.
  276. Take a look at gccenv.smp and decide if you have to change the defaults. If you
  277. don't use EMX, you will most probably have to change the name of the debugger,
  278. if your make-utility has a different name than "make" you will also have to
  279. change the appropriate constant.
  280.  
  281. Note that editing gccenv.smp is not enough, EPMGCC needs a file called gccenv.e!
  282.  
  283.  
  284. Compiling the macros:
  285. ~~~~~~~~~~~~~~~~~~~~
  286.  
  287. First, switch to your epm directory. If it makes you feel comfortable, make a
  288. backup copies of epm.ex and extra.ex. Then issue the following commands:
  289.  
  290. etpm epm /V
  291. etpm extra /V
  292. etpm gccproc /V
  293.  
  294. The /V-switch shows all macro source files included in the module. ETPM will
  295. complain about all errors with line and column number. If all your paths are set
  296. up correctly and if MYCNF.E doesn't contain errors, there should be no errors
  297. reported.
  298.  
  299. You should now be ready to use EPMGCC. For a test, start the editor, load a
  300. c-source file into the edit-ring, edit it to include errors and press c-F12 (or
  301. use the drop-down menu). After gcc has finished, press a-q once (this takes you
  302. to the error-file) and after examining the errors press a-q again. This takes
  303. you to the first error. Repeat pressing a-q to take you from error to error. At
  304. any time, you can switch to the current error-file with the menu-selection "View
  305. results" (there might be more than one error-file with the same name in the
  306. edit-ring). If you want to go to a specific error, put the cursor on the line
  307. reporting the error and press a-q.
  308.  
  309.  
  310. Final notes:
  311. ~~~~~~~~~~~
  312. In general, it is not a good idea to change the source code of the standard
  313. macros. But if you want to use the C syntax assist supplied with EPM also for
  314. C++ source files with the extension ".cc", you have to change in the file
  315. ckeys.e the following line (line 30 in my copy):
  316.  
  317.    if load_ext='C' or load_ext='H' or ... or load_ext='SQC' then
  318.  
  319. to
  320.  
  321.    if wordpos(load_ext,'C CC H CPP CXX SQC') > 0 then
  322.  
  323. or add "or load_ext='CC'".
  324.  
  325. I hope EPMGCC is of value for you.  If you think you have found a genuine bug,
  326. or would like to make suggestions, contributions, or enhancements to this code
  327. please drop me a note.  Since I have released this code without charge, I cannot
  328. offer a warranty or customer support, but I will do my best within the limit of
  329. available time.
  330.  
  331. English is not my native language. Nevertheless, I hope the documentation is
  332. clear enough to be of use. Everybody is welcome to supply a corrected version if
  333. you feel it makes things clearer.
  334.  
  335. 1/28/94
  336. Bernhard Bablok
  337. D-82256 Fuerstenfeldbruck, Germany
  338. INTERNET: ua302cb@sunmail.lrz-muenchen.de
  339.